gform Version 1.1d User and Installation Guide

gform Installation and User guide.

A generic Web form handler utility.

Current version is 1.1d 10-Oct-95

Any changes to gform will hopefully make its way to the online copy of this document located at http://www.swin.edu.au/csit/gform.html

Introduction
How itworks. and a simple example

GET IT!

User guide

Supported INPUT fields.
Syntax of gform commands
Special characters
Variables
Delivery Methods
Reply URL
CGI environment variables

Installation guide.

Installing it.
The config file
Tilde '~user' expansion
Complete example

Introduction.

The problem with forms is that they all need their own program or script to handle the fields in the form and perform some sort of action. This can make the creation of simple questionaire type forms difficult for web information providers. Usually you want to collect submitted forms of this type in a file or send it via email to yourself or to someone else or even send it directly to the printer.

gform is a program that enables you to easily create these type of forms by using commands that are embedded inside the form HTML file. It then uses simple variable substitution to deliver the results.

If you have some experience with HTML and forms, you may want to look at the examples that come with 'gform' or the complete example at the end of this docco.This should give you a good idea how it works and how it is used.

Further information can be found in a book titled "The Web Server Book" ISBN 1-56604-234-8 which has a section on form creation and a description of gform 1.01

How it works.

The HTML specification says that comments in a HTML file should be enclosed by
''. Gform takes advantage of that and will interpret the tag '<!--GFORM ' as the start of a command. These tags are considered to be comments by the HTML browsers. These gform 'comment' tags can appear anywhere within the form HTML file.

Take a simple form example:

<html>
<title>A Simple Form</title>
<body>
<form method=POST action="/cgi-bin/handler">
Enter your name:<INPUT type="text" name="yourname"><br>
<INPUT type="submit" value="submit">
</form>
</body>
</html>

To handle this form, you need a script or program to interpret the input value(s) for you. In this case this is specified as '/cgi-bin/handler'. If you add input fields to this form you typically will also need to modify
/cgi-bin/handler'. Having one script or program for each form is obviously very cumbersome to maintain. More often then not, the person who writes the form is not a programmer and may find it difficult to write form handlers.

Here is the same example with 'gform' as the 'handler'

<html>
<title>A Simple Form</title>
<body>
<form method=POST action="/cgi-bin/gform">
Enter your name:<INPUT type="text" name="yourname"><br>
<INPUT type="submit" value="submit">
</form>
</body>


</html>

(The gform commands will be explained later)

When somebody submits this form and gave their name as "Joe Bloggs", then the following line is send to:
"nobody@swin.edu.au"

The persons name is: Joe Bloggs

You can easily add more INPUT tags and gform tags without having to change 'gform' itself.

Supported INPUT fields.

All the INPUT type tags defined in HTML v2.0 can be used.

TEXTAREA A variable is assigned with all the entered text including linefeeds.
SELECT A single value is returned from a list of options.
SELECT MULTIPLE A comma separated list of the selections is returned.
CHECKBOXES The value of the checkbox is returned if selected. Otherwise "null" is returned.
RADIO BUTTONS The value of the selected radio button is returned. Otherwise "null" is returned.

See the complete example for usage of these.

Syntax of gform commands.

The are 3 types of gform commands. The first handles text and variables, the second defines a delivery method. and the third is an optional reply URL that is send to the user after they submit the form.

The syntax can be summarized as:

Where;

bold text is a keyword that must be entered.
Text between "<>" brackets indicates required data.
Vertical bar "|" reads as an 'exclusive or'
Square brackets "[]" encloses optional data.
"text" is a series of alphanumeric characters and $(var) is a variable. Any number of variables and text can be freely mixed.

Special Characters

Within gform text strings there would be no way to handle certain characters because they either have special meaning to gform or they simply can't be entered from the keyboard. To handle these characters we precede certain letters with a backslash character.

Here is the list of escaped characters with special meaning within gform text.

\n - newline
\t - tab
\f - form feed
\r - return
\$ - Escape a dollar sign
\" - Escape a double quote
\\ - Escape a slash

The most useful one is the Newline character. For example take the next 2 lines;

This will be returned as: "The quick brown foxjumped over the lazy dogs"

But by inserting newline characters,

we get

"The quick brown fox
jumped over the lazy dogs"

The complete example shows various use of escaped characters.

Variables

Variables are identified by a '$" sign and maybe enclosed with brackets so that you don't have to have a space between it any text immediately following it. A variable should match with the name given in the input specification. or it can be a CGI environment variable.Variables are case insensitive except for CGI environment variables.

For example a typical line in a form maybe.

Enter your name:<INPUT TYPE="text" name="myvar">

The Variable name is given by 'name' and is called 'myvar'.
The corresponding gform line could look something like;

$(myvar) is then replaced by what the form user entered and the result is delivered according to the given delivery method(s).

There are 2 special variables that are always defined. $(date) and $(time) that return the current date and time.

Delivery methods.

There are 3 ways you can get the information from a submitted form. These are email, to a printer or in a text file. Any combination of delivery methods can be used.

To get the results send to you via email you use

The "<!--gform " lines with the text and variables you have specified, will be send to "address@some.site.edu" via email. The variables ofcourse will contain the entered values.

You can optionally also include a subject

The double quotes in the <!--gform lines are required.

To get the results appended to a file you use

Be aware that the web server owner must have write access to the file. Typically a web server runs as user
"nobody"

To send the results directly to a printer, you would use

Where queue is the name of a printer on the system. For BSD type UNIX , the queue corresponds to an entry in the '/etc/printcap' file. If you have a printer with special forms, you maybe able to construct gform
text commands that put the text in the right places on the paper form.

Also note that the results are send as straight text and not in some nicely formatted postscript.

Reply URL

After the user has submitted the form, the form creator has the option of specifying a URL to send back. This is done by using the 'reply' command. By default a simple "Thank You" will be send.
For example;

<!--gform reply="/mythanks.html">

CGI environment variables.

If a variable specification in a <!--gform line doesn't match any in the INPUT specification, then it will interpret it as an environment variable. If it is not an environment variable, it returns the word "null"
Here are most of the CGI environment variables currently recognized:

ANNOTATION_SERVER
AUTH_TYPE
CONTENT_LENGHT
CONTENT_TYPE
DOCUMENT_ROOT
GATEWAY_INTERFACE
HTTP_ACCEPT
HTTP_REFERER
HTTP_USER_AGENT
PATH_INFO
PATH_TRANSLATED
QUERY_STRING
REDIRECT_URL
REDIRECT_REQUEST
REDIRECT_STATUS
REMOTE_ADDR
REMOTE_GROUP
REMOTE_HOST
REMOTE_IDENT
REMOTE_USER
REQUEST_METHOD
SCRIPT_NAME
SERVER_VERSION
SERVER_SOFTWARE
SERVER_NAME
SERVER_PORT
SERVER_PROTOCOL

The value of these variables can also be seen in when using the "test-cgi" shell script that comes with the
standard CGI distribution.

See www.yahoo.com for an explanation of what they all mean.

Installing gform.

Gform is deigned to run on a UNIX system that has a C-Compiler.
The following steps will build the program on a UNIX system.

If you want to use 'gcc', edit the Makefile.
Check the config.h file and edit if required (see below)
Type 'make'
Copy 'gform' to a directory that has permissions to run scripts and programs. This is
typically 'cgi-bin'
Test it out by grabbing one of the sample HTML files and modifying it if required.

gform been developed on a DEC Alpha OSF/1 V3.0 using DEC 'cc' and ;'gcc-2.6.2'
I also tested it on a Sun running SunOs 4.1.3 with 'cc' and gcc-2.6.3
I haven't heard of any UNIX systems on which it doesn't run. If there are some fixes needed to make it
run on your system, let me know and I will include the fixes or porting bits.

I generally make changes as I get ideas or people make suggestions or report problems. Since it is a trivial application, I will make the code available just about straight away when its shown that changes work on my systems. Any changes doesn't necessarily mean a version number change although you should find notes on changes at http://www.swin.edu.au/csit/gform.html . Date references are a better indication.

The config file.

The "config.h" file holds various parameters that may need to be correctly set for gform to work.

If you want "~user" expansion then set USERDIR This is the path name to the users home directory. If it is defined with something then '~user' expansion is automatically enabled and the specified path is appended to the users home directory (see Tilde '~user' expansion section ).

MAIL The pathname of the 'binmail' program, in most cases the default definition will work ok.

PRINTCMD This is the pathname to the print command. The default is lpd style printing.

PRINTQ -This should be set to the switch on the print command that specifies the print queue

If you get an error message that says "Can't get DOCUMENT_ROOT" then you can try to define
WEBROOT in the config file. Set this to your Web document root directory, recompile and try again.

Tilde '~user' expansion.

You will sometimes see URL's with a '~user' syntax as part of the link. What this usually
does is expand that to the real path to a users home directory on the system that the server runs. This is a convenient way to enable users of a system to create their own web pages in their home directories.

Gform has the option at compile time to enable '~user' expansion or not to. If the configuration option "USERDIR" is defined then that will enable '~' expansion. If it has a directory name, then that directory name will be the public sub-directory for the user to put their web stuff in.

For example the user "fred" has a home directory of "/home/people/fred" and USERDIR is defined as "www".
This makes "/home/people/fred/www" publicly accessible via the local web server as:

http://www.some.system/~fred

The user Fred puts his web pages in his 'www' subdirectory. The rest of his home directory remains secure and inaccessible via the local web server.

Complete example.

The example here is included with gform as sample3.html. It demonstrates the various INPUT tags and how
gform can be used with these. To have a look at this form in action click here.

For demonstration purposes the file that the results are collected in is also the reply file. So when this form is submitted, you can get to see the results straight away. You will also note that the ACTION line specifies "gform-gate". This is just a shell script front end who's only job is to remove the previous reply file. Keeping in mind that delivering to a file actually appends. I guess you could include some HTML in the gform text lines and build a fancy reply file on the fly which you could show to the user. At the same time you also deliver the results via mail.

<HTML>
<HEAD>
<TITLE>gfrom sampler</TITLE>
</HEAD>
<BODY>
<H2>gform form sampler</H2>
<P>
Here are some different form specifies that will work with gform
version 1.1 (6-oct-95) <BR>
You may have to edit the FORM method... line according to your
local setup.
<FORM method=POST action="/swin-bin/gform-gate">
<HR>
<P>
Some regular text input fields
<P>
What is your name: <INPUT NAME="name" VALUE="" ><BR>
Your email address:<INPUT NAME="email" VALUE="" ><BR>
<HR>
<P>
Single choice select option:
<P>
What do you want to drink ? <SELECT NAME="drink" >
<OPTION>nothing
<OPTION>coffee
<OPTION>tea
<OPTION>juice</SELECT><HR>
<P>
Using multiple choice select options:
<P>
What do you want on your pizza ? <BR>
<SELECT MULTIPLE NAME="pizza">
<OPTION VALUE="ham">ham
<OPTION VALUE="cheese">cheese
<OPTION VALUE="tomato">tomato
<OPTION VALUE="capsicum">capsicum
<OPTION VALUE="chili peppers">chili peppers
<OPTION VALUE="mushrooms">mushrooms
<OPTION VALUE="olives">olives </SELECT>
<BR>
<INPUT TYPE="RADIO" NAME="size" VALUE="Small"> Small (6")<BR>
<INPUT TYPE="RADIO" NAME="size" VALUE="Medium">Medium (8")<BR>
<INPUT TYPE="RADIO" NAME="size" VALUE="Large">Large (10")<BR>
<BR>

Here are some checkboxes
<P>
<INPUT TYPE="CHECKBOX" NAME="salt" VALUE="yes"> salt<BR>
<INPUT TYPE="CHECKBOX" NAME="pepper" VALUE="yes"> pepper<BR>
<BR>
<HR>
<P>
Here are some radio buttons:<BR>
Please select your subscription length: <BR>
<HR>
<P>
A textarea
<P>
Please let us know what you think of our service by entering your
comments in the space provided<BR>
<TEXTAREA NAME="comments" ROWS=5 COLS=40>
</TEXTAREA>
<P>
<INPUT type="submit" value="send"> <INPUT TYPE="RESET"> <HR>
<P>
Last modified: 7-Oct-95 HR<HR>
<P>


























</FORM>
</BODY>
</HTML>

Here is the "gform-gate" script

#!bin/sh 
if [ -f /cwis/tmp/fred.html ]; then	
rm /cwis/rmp/fred.html
fi

/cwis/swin-bin/gform "$*"

Swinburne University home
This document maintained by Harry Raaymakers
Disclaimer
Last updated: 9-Oct-95